---
title: Document
summary: API reference for Document.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-17
library: PdfAPI.Core
reference_type: package
---

# Document

`Document` is the in-memory and on-disk representation of a single file participating in a PDF operation — every request (`ConvertRequest`, `MergeRequest`, `ExtractPagesRequest` via `DocumentRange`) and every `PdfResult` carries one or more `Document` instances. It can hold its bytes purely in memory, purely on disk, or both, and its constructor is `internal` (with a `[JsonConstructor]` companion), so instances are created only through the static factory methods or JSON deserialization, never `new Document()` directly. Disposing a `Document` deletes its backing file from disk.

## Purpose
- Carries a file's bytes and/or on-disk path, plus a generated `Guid` identity, through every PDF operation in the library. ([BR-19](../../business-rules.md#br-19-new-documents-receive-a-new-guid-identity))
- Loads bytes on demand from memory or disk. ([BR-05](../../business-rules.md#br-05-document-load-requires-in-memory-or-on-disk-bytes))
- Persists itself to a destination directory and removes its backing file, including as a side effect of disposal. ([BR-22](../../business-rules.md#br-22-saving-a-document-writes-to-destination-directory), [BR-23](../../business-rules.md#br-23-document-deletion-never-throws), [BR-24](../../business-rules.md#br-24-disposing-a-document-deletes-its-file))

## Context
- Namespace: `PdfAPI.Core`
- Assembly/package: `PdfAPI.Core`

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| FilePath | `string FilePath { get; set; }` | The on-disk path this document was loaded from or last saved to. |
| FileName | `string FileName { get; }` | Composed as `{Id}.{FileExtension}`; the canonical file name for this document. ([BR-21](../../business-rules.md#br-21-document-file-name-convention)) |
| File | `byte[] File { get; set; }` | The document's in-memory bytes, when loaded. |
| FileExtension | `string FileExtension { get; }` | The file extension (without leading dots) used to compose `FileName`. |
| Id | `Guid Id { get; }` | The document's generated identity, assigned at construction. ([BR-19](../../business-rules.md#br-19-new-documents-receive-a-new-guid-identity)) |
| SourceSystemId | `string SourceSystemId { get; set; }` | Caller-supplied identifier correlating this document back to an originating system. |
| Load() | `bool Load()` | Materialises `File` from disk when not already in memory; returns `false` when neither in-memory bytes nor an existing `FilePath` are available. ([BR-05](../../business-rules.md#br-05-document-load-requires-in-memory-or-on-disk-bytes)) |
| Load(string, bool) | `static Document Load(string sourceFilePath, bool mustExist = false)` | Creates a `Document` from a file path, reading its bytes when the file exists; throws when `mustExist` is true and the file is absent. ([BR-20](../../business-rules.md#br-20-missing-file-load-behavior)) |
| Load(byte[], string) | `static Document Load(byte[] file, string fileExtension)` | Creates a `Document` directly from an in-memory byte array and extension. |
| CreateEmpty(string) | `static Document CreateEmpty(string fileExtension)` | Creates a new `Document` with a fresh identity and no bytes yet assigned. |
| Save(string) | `void Save(string destinationDirectory)` | Writes `File` to `{destinationDirectory}\{FileName}` and updates `FilePath`. ([BR-22](../../business-rules.md#br-22-saving-a-document-writes-to-destination-directory)) |
| Delete() | `bool Delete()` | Deletes the file at `FilePath` when it exists; swallows any exception and returns `false` on failure. ([BR-23](../../business-rules.md#br-23-document-deletion-never-throws)) |
| Dispose() | `void Dispose()` | Calls `Delete()`, removing the backing file as a side effect of disposal. ([BR-24](../../business-rules.md#br-24-disposing-a-document-deletes-its-file)) |

## Behavioral notes
- The constructor is `internal`, so package consumers can only obtain a `Document` via the static factories, via a `PdfResult`/`DocumentRange` returned from `PdfClientService`, or via JSON deserialization.
- `Save` composes its output path with a hard-coded `\` separator rather than `Path.Combine`.*
- `using (var doc = Document.Load(path))` over a `Document` is destructive: exiting the `using` block deletes the file at `FilePath`. ([BR-24](../../business-rules.md#br-24-disposing-a-document-deletes-its-file))

## Constraints and usage notes
- Do not wrap a caller-owned source file's `Document` in a `using` block unless deletion of that file is intended.
- Call `Load()` before reading `File` if the document was constructed from a path rather than bytes.

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## Related documentation
- [Index](../../index.md)
- [Overview](../../overview.md)
- [Architecture](../../architecture.md)
- [Dependencies](../../dependencies.md)
- [Operations and processes](../../operations-processes.md)
- [Business rules](../../business-rules.md)
- [Security and authorization](../../security-authorization.md)
- [API reference](../index.md)

## Sources
- `PdfAPI.Core\Document.cs`